class: center, middle, inverse, title-slide .title[ # Report Template ] .subtitle[ ## Introduction of {unhcdown} package ] .date[ ### <a href="index.html"><i class="fa fa-indent fa-fw fa-2x"></i></a> ] --- # Learning objectives * Work with Report to enable full reproducibility * Understand the type of reports * Rmd & Quarto --- ## Most science is not reproducible  ... even within the same lab group over time! > Your closest collaborator is you 6 months ago, and you don't respond to emails. <small>P. Wilson</small> --- ## Research workflow 1. Prepare data (**EXCEL**) ***  --- ## Research workflow 1. Prepare data (**EXCEL**) 2. Analyse data (**R**) ***  --- ## Research workflow 1. Prepare data (**EXCEL**) 2. Analyse data (**R**) 3. Write report/paper (**WORD**) ***  --- ## This workflow is broken  --- ## Problems of a broken workflow - How did you do this? What analysis is behind this figure? Did you account for ...? - What dataset was used (e.g. final vs preliminary dataset)? - Oops, there is an error in the data. Can you repeat the analysis? And update figures/tables in Word! > A scientific article is advertising, not scholarship. The actual scholarship is the full software environment, code and data, that produced the result. <small>Claerbout & Karrenbach 1992</small> --- ## Leave behind your current workflow  --- ## Rmarkdown to the rescue!  knitr - pandoc - Rstudio --- ## Rmarkdown documents * Fully reproducible (trace all results inc. tables and plots) * Dynamic (regenerate with 1 click) * Suitable for + documents (Word, PDF, etc) + presentations + books + websites + ... --- ## What is R Markdown? * R Markdown is an authoring format that combines code, text, and results in a single document. * It allows you to create reports, presentations, and dashboards with R code and text. ## Basic Structure ```markdown --- title: "My Report" output: html_document --- # Section 1 This is a text section. ``` --- ## Enable a fully auditable workflow As soon as all steps (i.e. **DATA + TIDYING + MODELING + VISUALS + NARRATIVE**) are done through **series of written commands recorded in scripts**: - when spotting error in the data, or using different dataset, one just need to adjust in the script and report will update automatically; - Data manipulation becomes be *de facto* fully documented (no more manual changes in Excel); - Analysis is self-explanatory and ready for any kind of collaborative review; - Customization are facilitated and allow to deliver final product with a professional branding and styling. > Analysis becomes streamlined and [reproducible](https://unhcr-americas.github.io/reproducibility)! > A "collaboration mode" is enabled from the begining of the process! > As your analysis can be reviewed, you become "covered"... ??? instead of **hundreds of mouse clicks** See also http://muschellij2.github.io/summerR_2015/modules/module12.html --- ## unhcrdown [unhcrdown](https://github.com/vidonne/unhcrdown) provides a set of templates following UNHCR Brand recommendations. The goal of this package is to ease and speed up the creation of reports, presentation and website while promoting the UNHCR visual identity. .pull-left[ **Content** 1. Microsoft Word document 2. HTML to PDF paged reports 3. Microsoft PowerPoint presentation 4. HTML slides ] .pull-right[ * Add organization logos and headers. * Maintain a consistent look across reports.  ] --- ## Reproducible pipelines with R markdown <img src="data:image/png;base64,#img/tools_change_new.svg" width="70%" /> --- ## Reproducible pipelines with R markdown <img src="data:image/png;base64,#img/reproducible_flow_tools.svg" width="100%" /> --- ## Reproducible pipelines with R markdown <img src="data:image/png;base64,#img/reproducible_flow_r.svg" width="100%" /> --- ## Notebook for Data Insights .pull-left[ > Insight: The capacity to gain an accurate and deep understanding of someone or something Not all charts will emulate need for interpretation - the data analyst need to gemerate the one that can create __debates__. Charts need to be __crafted__ - for instance use chart title framed as "opening question"... Insights arive when a multifunctional team is able to explain __unexpected patterns__, to challenge or revise __existing assumptions__, or to identify evidence to support __Call to action__. ] .pull-right[ .img[] ] ??? https://www.ictworks.org/wp-content/uploads/2021/02/usaid-guide-artificial-intelligence.pdf https://bluemoondigital.co/our-blog/5-elements-storytelling-data/ Check the analysis repo: http://analysis.unhcr.org --- ## Notebook to communicate with data: Microsite .pull-left[ <span style='font-size:30px;'>From __assumptions to evidence__ based statement</span> Data is to support Narrative - not the other way around! Leverage Art Data Storytelling to: * __Explain__, * __Enlighten__, * __Engage__ ] .pull-right[ .img75[] ] ??? See https://github.com/unhcr-americas/ageingonthemove/blob/main/README.md https://distill.pub/2020/communicating-with-interactive-articles/#applications-tab Research Dissemination Conducting novel research requires deep understanding and expertise in a specific area. Once achieved, researchers continue contributing new knowledge for future researchers to use and build upon. Over time, this consistent addition of new knowledge can build up, contributing to what some have called research debt. Not everyone is an expert in every field, and it can be easy to lose perspective and forget the bigger picture. Yet research should be understood by many. Interactive articles can be used to distill the latest progress in various research fields and make their methods and results accessible and understandable to a broader audience. Opportunities Engage and excite broader audience with latest research progress Remove research debt, onboard new researchers Make faster and clearer research progress Challenges No clear incentive structure for researchers Little funding for bespoke research dissemination and communication Not seen as a legitimate research contribution (e.g., to the field, or one's career) --- ## Conclusion & Key Takeaways * R Markdown is a versatile tool for report generation. * Parameterized reports enable dynamic customization. * Automate report generation for efficiency. * Customize and brand reports as needed. --- class: inverse, center, middle # Thank you ### Questions? [post Feedback here](https://github.com/unhcRverse/unhcrverse/issues/new?assignees=&labels=enhancement&projects=&template=comment_prex_2_tidyverse.md&title=%5Blearn%5D) --- ## Some useful links .pull-left[ - [Rmarkdown by RStudio](http://rmarkdown.rstudio.com/) - [Rmarkdown cheat sheet](http://www.rstudio.com/resources/cheatsheets/) - [Initial steps toward reproducible research](http://kbroman.org/steps2rr/) - [Course on Reproducible Research by K. Broman](http://kbroman.github.io/Tools4RR/) - [Reproducible Research in Coursera](https://www.coursera.org/course/repdata) - [Nice R code](http://nicercode.github.io/guides/reports/) - [Reproducible Research with R and RStudio](http://christophergandrud.github.io/RepResR-RStudio/) - [Ten simple rules for reproducible computational research](http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1003285) ] .pull-right[ - [CRAN Task View on Reproducible Research](http://cran.r-project.org/web/views/ReproducibleResearch.html) - [knitr](http://yihui.name/knitr/) - [pandoc](http://johnmacfarlane.net/pandoc/) - [pander](http://rapporter.github.io/pander/) - [rapport](http://rapport-package.info/) - [reports](http://cran.r-project.org/web/packages/reports/index.html) - [Rgitbook](http://jason.bryer.org/Rgitbook/) ]